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User Experience with Online HELP 


by Stacy Jackson, CUN 


My experience with online documentation is in writing 
online help and news. I maintain a large database for the help 
system in CMS at Cornell University. 

The problem I've found with writing online documentation 
isn't writing it per se; you write it the same way you write 
anything technical - as clearly and succinctly as you can. The 
problem is organizing your online information so that people 
who need it can find it. People don't want to have to learn to 
use help, and they don't want to hunt around - they want. the 
information they're after to appear magically on their screens. 
They want the computer to understand their questions when ex- 
plained in English, and the computers I've seen aren't very 
good at that yet. 

I haven't been able to prepare help so that it works for 
the total beginner. When I first began writing help informa- 
tion, I spent a lot of time refining the language so that it 
would be intelligible to anybody. Once I thought I had done 
so, I found that beginners still couldn't use help as a learn- 
ing device. They couldn't find the information they wanted. 
Once they found it, they were terrified by the syntax diagram, 
or they tried to copy the examples exactly as they appeared, 
without substituting a filename for fn as instructed. The 
beginners I talk with express a preference for printed docu- 
mentation anyway, as they are not vet comfortable with the 
computer. Help begins to become helpful as soon as the reader 
has grasped some basic concepts, such as what a "command" is 
and what a "file" or "dataset" is. Help is, in fact, most 
useful for refreshing your memory about something you already 
understand. 

The idea of different HELPs for people at different levels 
of expertise is appealing. There are two possible ways to do 
this: 

@e Keep a profile for each user. This could simply indicate 


"beginner," "intermediate" or "advanced." To be more 
complete, it would indicate "beginner at PL/I," “advanced 
at FORTRAN" - but this would be a nightmare to set up 


and maintain. 
e Provide different commands to request different levels 
of HELP. You could, for instance, instruct beginners 
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to type "explain fortran," and more experienced users to 
enter "remind fortran." A problem with this method is 
that it requires people to learn more about HELP than 
they otherwise would. I suspect that many people would 
continue to use whichever command they first became fam- 
iliar with, even when it was no longer the best choice 
for them or for their circumstances. 

Your HELP processor can assist you in finding out how peo- 
ple are using it by keeping records of every request for help. 
At Cornell I look through histograms of such records every month. 
When I see the same error cropping up over and over, I know it 
isn't the users' fault - it's the HELP system which needs help. 
What can I do about it? 

First, I try to provide a redundancy of paths to the same 
information. Cornell's HELP processor, written by Larry Chace, 
allows me to cross-reference a particular item by as many key- 
words as I like. So when I find a’ common error I can adda 
pointer to the correct HELP information, if I can identify what 
the user was trying to ask. Common errors include: 

e Spelling out abbreviations, e.g. typing BREAKDOWN or 

BREAK DOWN for a command called BRKDOWN. 

@e Misspelling the names of commands that look like alpha- 

bet soup. 

e Using the corresponding name for the command on another 

system, if your installation runs more than one system. 
To be most effective, HELP information should be cross-indexed 
in every possible direction. Systems that have HELP almost al- 
ways allow you to look up detailed information about a command 
if you know the command's name. But can you look up a com-: 
mand's name if you know what you want to do? If what you want 
to do requires a sequence of commands, can you look up the se- 
quence? Is there a glossary of the terms used in explaining 
the commands? 

The problem is keeping all this cross-indexed information 
up to date and in synch. Does this start to sound like a 
database application to you? It does to me. 

If you can reduce to a minimum the amount the user needs 
to know in order to get help with a problem, you will have 
gone a long way toward producing more effective online docu- 
mentation. 
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This document was originally presented at SHARE 57 in 
Chicago under the Documentation Project. A lot has 
happened in the industry since that time and some 
additions have been made to the original paper to reflect 
those changes. 


0.1 DOCUMETRICS: 
"THE SCIENCE OF GOOD USER DOCUMENTATION' 


Online and printed documentation have many aspects in common. 
The fundamentals of good documenation, including good human 
factors, apply regardless of the medium. However, simply 
putting machine-readable manuals on line that were intended 
for the printed page is a disservice to users and a misuse of 
resources. It is also the abdication of responsibility by 
both the authors of the software--if this was an intentional 
part of the system's design--and computer center personnel--if 
this is the way they attempt to solve problems of 
distribution. Documentation intended for the printed page 
must be restructured for the various online environments. 
Likewise, documentation written for terminal accesss is 
unsuited for the printer. 


0.2 Types of Printed Documentation 


Printed documentation is written to accomplish three basic 
purposes: 


e Tutorial. You lead the reader in a front-to-back manner 
through the use and capabilities of the system. There is 
usually an implicit hierarchy to the entire manual and a 
hierarchy to each of the discussions by chapter and section. 
You devote time and space to introducing a subject and then 
treat it in detail. 


2 Human Factors 


e Reference. The organization is topical and explanations 
brief. The reader is expected to move about within the 
document as needed in order to pick out necessary details. 
Organization may be alphabetical by command/feature rather 
than strictly topical. 


e Pocket Guide. You provide the reader with syntax including 
options, defaults, and limitations. You can assume a great 
deal about what the reader already understands. 
Organization is usually alphabetical. 


e Newsletter. The information is timely. You keep users up- 
to-date on changes or problems with the system, including 
pending new releases. 


Most printed documents try to be both tutorial and reference 
with varying success. With the growing popularity of pocket 
guides and online help facilities, printed manuals can and 

should lean more toward the role of tutorials and self-study 


guides. 


0.3 Types of Online Documentation 
Online documentation appears in four formats: 


e Error. Perhaps the most overlooked source of online 
documentation is help messages. Whereas many error messages 
are cryptic and say only that an error has occurred, you 
should give the user complete information on what has 
happened and an equally complete set of guidelines for 
resolving the problem. 


e Help. Tell the user what can be done at the point in the 
interaction where help is requested. Help is usually in the 
form of syntax, options, and defaults. 


e Explanation. Explain a general topic in a brief but 
Standalone manner. Downplay syntax in favor of an overali 
view of the appropriate context or component of the system. 


e Tutorial. Lead the user through the system or some 
component of the system in what is probably a question and 
answer mode. Precede each interaction with a brief 
explanation of the question and possible answers. Include 
real examples wherever possible. 


e News. Provide the ability for the system to display up-to- 
date information to users. You might also think about 
including user-to-user communications. 


Most systems try to provide help, explanations, and tutorials 
in the same facility, which means they generally fail at one 
Or more. Your top priority should be to develop online help 
facilities tailored to the context within which the user needs 
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or requests assistance. This usually means the more than one 
facility must be designed. At least two are required: error 
messages and some form of help-on-request, but don't try to 
make the latter explanatory and tutorial as well. 


0.4 STYLE AND COMPOSITION 


It may come aS a surprise that there is very little we don't 
already know about writing technical documentation that 
doesn't come to us instinctively or from fields outside data 
processing, but only if we are willing to see beyond the 
specifics of our own prohlems and remove the shroud of mystery 
Surrounding computers. The following discussion of style and 
composition is formed around The Elements of Style by William 
Strunk Jr. and E.B. White (3rd edition; MacMillan Publishing 
Co.; New York; 1979.) 


While it seems that the types of printed documentation 
accomplish the same tasks as the types of online 
documentation, they are comparable in purpose only. The 
context of online documentation--the medium itself--is quite 
different and therefore the style of writing changes 
drastically. In designing and writing online documentation, 
emphasize brevity and specificity and explore a different 
organization because the terminal screen is not the place to 
read standard text. 


0.5 Style of Writing 


Online documentation is subject to the same style rules as 
printed documentation, with some alteration in priorities. 


e Write in a natural way. Use words and phrases that come 
readily to mind. Use jargon only when necessary and then 
explain it. Also, use orthodox spelling; saving space at 
the expense of ready comprehension defeats the entire 
purpose. 


e Use nouns and verbs. Adjectives and adverbs are usually 
unnecessary. Beginning an explanation with a command is 
sometimes most appropriate (e.g., ENTER ? FOR HELP.) 


e Revise and rewrite. If you want to miss the mark, send 
something out without at least one other person's review. 
Others see problems you don't. If it is online 
Gocumentation, review it on the screen, not on the printed 


page. 


e Don't overstate. Readers can learn to distrust and ignore a 
barrage of emphatic warnings. Don't use and exclamation 
point or begin everything with "Note that;" they soon wear 
out and lose their impact. 


4 Human Factors 


® Don't be breezy. Humor works only once, if at all. Cute 
messages like "I AM CONFUSED" make the system seem stupid or 
cynical rather than friendly. 


0.6 Composition rules 


Online documentation is subject to the same composition rules 
as printed documentation, with slightly different emphasis on 
the first point: 


® Use the active voice and talk to the reader. Stronger 
sentences are shorter. You can avoid he/she/user problems. 
Also, keep to the present tense, particularly in the online 
context since the action takes place immediately. Don't say 
"ABC WILL EXECUTE UPON COMMAND...":; say "ABC EXECUTES ON 


COMMAND...” 


e Choose a design and stick to it. Familiarity aids 
understanding and immediate recognition. Use parallel 
constructions so the reader recognizes more readily the 
content and function. 


e Use the positive form. Tell the user what is, not what. 
isn't. Don't let the system respond with "'H&*@ INCORRECT": 
have it say "HOME, UP, DOWN ARE CORRECT RESPONSES." Don't 
use should, could, might, may, etc., except for real 
uncertainty. "REENTER" has a lot more power than "YOU MIGHT 
TRY REENTERING." 


e Use definite, specific, and terse language. Emphasize words 
at the beginning of the sentence. "HOME, UP, DOWN ARE 
CORRECT RESPONSES" is better than "CORRECT RESPONSES ARE 
HOME, UP, DOWN". 


0.7 FORM 


The medium itself dictates the form of the message in some 
ways and enhances it in many ways. Since this paper is 
primarily about online documentation, the terminal medium 
governs the form. . 


Borrowing from the publishing profession, particularly the 
newspaper industry, online documentation is very much akin to 
the hard news story and printed manuals are akin to feature 
stories. We can learn a great deal from these analogies. For 
a good discussion of form as well as style and composition, 
see Editing in the Electronic Era by Martin L. Gibson (Iowa 
State University Press; Ames, Iowa; 1979.) 
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0.8 The Printed Page 


When you write for the printed page, you are less restricted 
by format, size, shape, and length, and you should take 
advantage of this flexibility. 


e Order. The order of presentation is less restricted since 
the eye is free to move anywhere on the page. You can 
follow the classic introduction/body/conclusion form within 
each chapter and section, and each discussion can usually 
take as much space as needed. 


e Shape. You can interchange type sizes and fonts for more 
flexible formatting. However, follow the style rules of 
consistent design and don't get so fancy that you loose the 
reader. Type size can be used to emphasize hierarchy and 
fonts can emphasize words and differentiate explanatory text 
from examples, etc. 


e Illustrations. You aren't limited to words to present an 
idea. You can use diagrams, illustrations, formulas, etc. 
This flexibility is still somewhat reduced for documentation 
produced by computer-driven typesetters, although great 
strides are being made to integrate graphics with text. 


0.9 The Online Context 


When you write for the terminal screen, you are restricted in 
Size and form. However, there can be advantages to the fact 
that online documentation Nn appears on a screen 
Since some of your choices are dictated. 


e Order. Since the point is to limit the reader's reading 
time, the terminal screen provides the clearest ordering of 
information according to importance. Most hard news stories 
are written in the inverted pyramid form, which means you 
should put critical information--the big end of the 
pyramid--at the top. Since the story tapers to smaller 
details, the story can be trimmed from the end. Likewise, 
the reader can stop reading or interrupt your message with 
minimal loss of information. Thus the analogy is made 
between the composer's scissors and the user's break or 
clear-screen key. 


e Length. For online documentation to be serviceable, it must 
be short. Under no circumstances should you write a message 
or text more than the average screen length. Even with 
scrolling and paging, messages should be much shorter than 
the full screen. Just as many readers only scan the first 
part of newspaper articles that are continued to inside 
pages, users generally absorb only what is immediately 
before them on the screen. Anything longer belongs on the 
printed page. 


6 Human Factors 


e Shape. With more terminals equipped with blinking and 
highlighted text, and even full color text, the tendency 
will be for authors of software to blitz the user with a 
flashy light show. Just as type sizes and fonts can be 
overused, highlighting and blinking can be far more 
distracting than informative. Follow rules of consistency 
and particularly restraint. 


® Illustrations. You can use illustrations in the online 
environment, but make them specific to the context and use 
the same restraint one shows with blinking and highlighting. 


The use of color, highlighting, illustrations, tokens, etc., 
in the online environment as integral aids to user assistance 
has not been fully explored. The major difficulty is that not 
all terminals and environments support these features. 
Therefore, the online environment may look different depending 
on the terminal or host system the user has. 


0.10 CONTENT 


In most online systems, if you know the system as a user, you 
know a lot more than you might imagine about the situation the 
user is in and why a problem has occured or why a question has 
been asked. This in fact is the real challenge to writing 
online documentation. The question you have to ask yourself 
is why the user made the error or why the user is asking for 
help (example, tutorial) at that point. If you can answer 
these questions, then you can write online documentation. 
Writing isn't the hard part, it's knowing what to write and 
which type of online documentation is proper. 


